Headless Web Kiosk Setup

Setting up a web kiosk on debian is a relatively simple proccess that only involves a couple steps.

Table Of Contents

Dependencies

You will need to install a browser, for this example we are using firefox as our headless web kiosk. If you have a mouse cursor, you will need to install Unclutter. Unclutter sets an idle timer where it hides the cursor.

Kiosk.service File

To start you need to navigate to the file path /etc/systemd/system/. From here you need to create a kiosk.service file. Then use your preferred text editor to open it. There are a couple ways you can create this file depending what you need. I’ll show two examples.

[Unit.]
Description=Firefox Kiosk Mode
After=network.target graphical.target lightdm.service

[Service]
User=xenter
Environment=DISPLAY=:0
ExecStart=/bin/bash -c "/usr/bin/unclutter -idle 3 & /usr/bin/firefox --kiosk --display=:0 --kiosk-monitor 0 INSERT_WEBSITE_HERE"
Restart=always

[Install]
WantedBy=graphical.target

In this scenario we do a couple things

  1. Unit defines that the kiosk should start after the network, graphical, and lightdm services are ready.

  2. Service defines the user, the environment, and the ExecStart command first points to the unclutter timer to run side by side with the kiosk. Then it points to the website kiosk telling it to run and then the website to display. Restart tells the service to automatically restart if it crashes or stops.

  3. Install tells the service to run in relation to the boot system process.

Now we will look at a slightly more complicated set up using a docker compose file, and running on localhost as the website.

[Unit]
Description=Firefox Kiosk Mode
After=network.target graphical.target multi-user.target

[Service]
Environment="DISPLAY=:0"
Environment="XDG_RUNTIME_DIR=/run/user/0"

# Start X server directly (more reliable than startx)
ExecStart=/usr/bin/Xorg :0 vt8 -keeptty -nolisten tcp

# Wait for X to be up before running xset and Firefox
ExecStartPost=/usr/bin/sleep 2
ExecStartPost=/usr/bin/xset -display :0 s off
ExecStartPost=/usr/bin/xset -display :0 -dpms
ExecStartPost=/usr/bin/xset -display :0 s noblank

# Start Docker Compose
ExecStartPost=/usr/bin/docker-compose -f /home/xenter/docker-compose.yml up -d

# Start Firefox in Kiosk Mode
ExecStartPost=/usr/bin/firefox-esr --display=:0 --kiosk-monitor 0 --kiosk http://localhost:3000

Restart=always
RestartSec=5

[Install]
WantedBy=graphical.target

Much of this kiosk.service file is the same as before. Let’s review the differences.

  1. Service Here we are still setting the display, but then pointing to a specific file directory under the root user.

  2. We start the X server directly now. For the ExecStartPost section this handles post commands that happen after the X server is started. This sets it to wait two seconds to start. Then disables screensavers, power-saving features, and no blank. All of this is to make the display run constantly.

  3. We start our local docker compose file, this gives us our web server. Then we start the kiosk server, and point to the localhost defined in our docker compose file.

Note: We do not use ExecStartPre. This is used for a one and done command that runs before the kiosk is started. This works well for setting environment variables, not for a concurrent service like unclutter.